home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Taifun / Taifun 036 (1987-11-15)(Ossowski, Stefan)(DE)(PD).zip / Taifun 036 (1987-11-15)(Ossowski, Stefan)(DE)(PD).adf / SiliCon / Sili.DOC < prev    next >
Text File  |  1989-01-18  |  22KB  |  450 lines

  1.                                                                    [8707.1]
  2.                              First Sili(Con:)
  3.                              ________________
  4.  
  5.  
  6.                             -- the Smart CLI --
  7.  
  8.  
  9.                       Copyright (C)1986, 1987 Pete Goodeve
  10.                         (for distribution conditions,
  11.                          see the end of this document.)
  12.  
  13.  
  14. This is a revised first release of Sili(Con:), a greatly enhanced CLI for
  15. AmigaDOS.  [yes, you're right -- it is an acronym of sorts...  It's a
  16. "Smart Input Line Interpreter", with its own "Control Console" window.
  17. Also I just kind of like silly names...]
  18.  
  19. Unlike the normal CLI, Sili(Con:) accepts DOS commands in a window
  20. of their own, with full editing facilities -- cursor positioning with the
  21. arrow keys, backspace left, delete right, and so on.  The program invoked
  22. by the command runs in the normal CLI Console window; any direct interaction
  23. with the program also takes place in this window.
  24.  
  25. A "History" of previous commands is maintained in the Command window.
  26. You can use the up and down arrow keys to bring any of these back for
  27. re-execution or re-editing.  You can also click on any visible command
  28. with the mouse to bring it back, or double-click to execute it. (More
  29. commands than are visible remain accessible with the arrow keys, but
  30. this first release has no way of paging them onto the screen, except
  31. by making the window larger.)
  32.  
  33. Other keystrokes -- described in detail below -- allow you to delete items
  34. from the history list, or add new ones without actually executing them.
  35. You can also activate the command window and bring it to the front with a
  36. keystroke, or quickly push it out of the way so the entire screen becomes
  37. visible.  You can work in the Control window at any time, even when a
  38. program is currently executing in the Console window: all the commands
  39. that you enter will be executed in sequence.
  40.  
  41. The Command Interpreter itself is also enhanced.  It checks the invoked
  42. command to see if it is a command script rather than a program: if it is,
  43. and takes no arguments, it will execute the commands in the script itself;
  44. if it is an "EXECUTE" type file, it will invoke the EXECUTE command
  45. -- renamed "X" in this release -- to interpret the arguments and commands.
  46. Other enhancements, including an "append" version of output redirection,
  47. are described below.
  48.  
  49. This software is donation supported.  Please read the Distribution
  50. information and conditions at the end of this document.
  51.  
  52.  
  53. Limitations
  54. ===========
  55.  
  56. Let's get these out of the way first, so we know where we stand.
  57.  
  58. First, this release only works with Workbench 1.2.  It was originally
  59. intended to be useable under 1.1 as well, but it would never be as
  60. convenient without the functions of 1.2 that it is able to use; in
  61. addition, there is some problem at the moment that makes it completely
  62. useless under 1.1.  Sorry.
  63.  
  64. Although it is perfectly possible to have a copy of Sili(Con:) in each
  65. CLI window you have open, each copy takes up about 32K (program plus
  66. workspace), so you probably will not want to do this.  Also you may get
  67. confused as to which Control window goes with which Program window, and
  68. furthermore the "awaken" keystroke will only work with the one you started
  69. first (though you can always use the mouse to awaken others).  This
  70. limitation is eased considerably by the ability to set up script files which
  71. automatically "RUN" programs such as editors, leaving the Control window
  72. available for further commands.  You can also invoke as many commands as
  73. you want at any time: they will be executed in sequence.
  74.  
  75. I have tried to make the NEED to use the mouse as small as possible
  76. (although it is often very convenient, and the option is always available),
  77. but there are times at which there is no alternative to its use; in
  78. particular, if you want to interact with the running program you will have
  79. to click in that window (unless the program has opened and activated its
  80. own).  Note too that if you are in the middle of typing a command when
  81. a program opens a window, the new window won't become active automatically.
  82. On the other hand, if you leave the mouse pointer in a convenient position
  83. you can "click" the left button with the Left-Amiga-ALT key combination.
  84.  
  85. Remember that when Sili(Con:) is running you don't type commands into the
  86. associated CLI Console window!  Anything you DO type into that window when
  87. no program is waiting for it will simply remain there until some later
  88. program reads from the Console.  As usual though, typing characters into
  89. the window will stop any more output showing in that window until they're
  90. cleared.
  91.  
  92. A final point: you can of course say "RUN commandname" to Sili(Con:),
  93. but RUN is simply a standard CLI, and doesn't know about any of Sili(Con:)'s
  94. added features.
  95.  
  96. And now on to the good stuff.
  97.  
  98.  
  99. Installing and Running Sili(Con:)
  100. ================================
  101.  
  102. The executable program is actually called "sili" for simplicity.  You should
  103. install it in your "C:" directory like any other DOS command.  Start it
  104. simply by giving the command "sili" to your DOS CLI; it takes over
  105. management of the CLI window it was invoked from until you terminate it
  106. again.
  107.  
  108. For proper operation in all circumstances, you will also have to rename
  109. (or copy, if you prefer) the DOS "EXECUTE" command to "X", as this is the
  110. name that Sili(Con:) expects for this program when it needs it.  This module
  111. is only used if you give Sili(Con:) a command invoking a script file with
  112. arguments; otherwise the program is totally self-contained.
  113.  
  114. You may also want to edit your "startup-sequence" file in the "S:" directory
  115. to execute "sili" as its final command, so that it becomes your standard
  116. interface to the system.  If you don't mind the memory space being occupied,
  117. you might also like to have your startup-sequence create a directory RAM:C,
  118. say, and transfer some frequently used command files to it. It should also
  119. add this directory to your path (see below), so that Sili(Con:) can find
  120. them.  This satisfies two major desires: things run faster, and you can do
  121. a lot of things without your system disk in the drive.  The DOS 1.2 "path"
  122. -- which Sili(Con:) takes full advantage of -- is a notable improvement in
  123. the flexibility of the system.
  124.  
  125.  
  126. Closing Down
  127. ============
  128.  
  129. To remove Sili(Con:) from the system, click on the "Close" box.  You will
  130. return to the standard CLI after any commands in progress have completed.
  131.  
  132. You may get confused if you give the "ENDCLI" command  to Sili(Con:).
  133. It will be ignored until you click in the close box, at which point both
  134. Sili(Con:) and the CLI window itself will terminate.
  135.  
  136.  
  137. Command Search Path
  138. ===================
  139.  
  140. Sili(Con:) is aware of, and uses, AmigaDOS 1.2's command file "path".
  141. However, unlike the CLI, it will find both program and script-file commands
  142. on that path (with restrictions noted below).  In addition, you can assign
  143. certain special "logical device names" to directories that Sili(Con:) will
  144. also search.  If some of the directories you've specified in the path or as
  145. logical devices are not at the moment available (because you've removed the
  146. disk containing them) Sili(Con:) ignores them in its search.
  147.  
  148. For those new to release 1.2 of DOS, the path is a list of directories
  149. that will be searched -- after the current directory, and before the "C:"
  150. directory -- for a filename that matches the command; the first one found
  151. will be executed.  You set up (and list) the path with the DOS "PATH"
  152. command.  See the 1.2 documentation for full details.
  153.  
  154. Sili(Con:) also searches directories ("logical devices") "C0:", "C1:",
  155. "C2:", "C3:", and "C4:" if they exist.  "C0:" is searched BEFORE your
  156. current directory; the others are searched, in order, after the current
  157. directory but before the path and the "S:" and "C:" directories.
  158. Use the "ASSIGN" command to assign these special names to the particular
  159. directories you want to search.  As an example, if you have some commands
  160. in "RAM:C" and others in "DF1:UTIL", you can make them accessible by:
  161.  
  162.           ASSIGN C1: RAM:C
  163.           ASSIGN C2: DF1:UTIL
  164.  
  165. Alternatively you can use a path:
  166.  
  167.           PATH RAM:C DF1:UTIL
  168.  
  169. The advantage of the first method is that you can easily reassign one
  170. directory without affecting others (after changing work disks for example)
  171. -- also it is required for some command script files (see below).
  172. The advantage of the second is that you don't have to be concerned as to
  173. which slots are already in use.  My approach is to set up the path (to RAM:C
  174. etc) with the startup-sequence and then leave it alone, and to have a "use"
  175. command script in the root directory of each work disk that I invoke when
  176. I insert the disk, which sets up C1: etc. as specific command directories
  177. for that disk.
  178.  
  179. Beware that there is a bug in the Amiga RAM: handler that makes it inadvisable
  180. to assign C0: to any directory in RAM:.  If you do this, Sili(Con:) may have
  181. difficulties with command pathnames containing ":" or "/".  (This ONLY
  182. happens with C0:, because it is searched before the current directory.)
  183.  
  184.  
  185. Command Script Files
  186. ====================
  187.  
  188. You do not normally have to explicitly use the "EXECUTE" command with
  189. Sili(Con:).  If you give a command which is in fact the name of a script
  190. file, it will be executed directly.  Sili(Con:) will attempt to interpret it
  191. itself as a simple sequence of DOS commands, unless the first non-blank
  192. line begins with a period.  In this case, it assumes that the file expects
  193. command line arguments to be substituted into the text, and calls "X"
  194. (the "EXECUTE" command renamed) to process it.
  195.  
  196. If a command script is one that Sili(Con:) must run via the 'X' command
  197. it should NOT be in the DOS 1.2 Search Path: it must be in the current
  198. directory, the "S:" (or "C:") directory, or one of the logical devices
  199. "Cn:" discussed above.  On the other hand, directly executable script
  200. files MAY be in directories on the path.
  201.  
  202. Within a command script you can give any command that Sili(Con:) would
  203. accept from the Control Window -- even if the "X" command is invoked,
  204. because once the arguments have been substituted the command list is
  205. passed back to Sili(Con:) for execution.  However you should not nest
  206. another script file name except as the last item in the sequence:
  207. execution terminates at the first end-of-file encountered.  To invoke
  208. another script file from within a script, use "X" explicitly.
  209.  
  210. Note that the "S:" directory is searched before the "C:" directory, so you
  211. can have a script file that supersedes a DOS command with the same name.  If
  212. the script references the DOS command itself it must use a full path name.
  213. As an example, "S:ED" could contain:
  214.  
  215.         .k text
  216.         run c:ed <text$text.temp>
  217.  
  218. This simply brings up the editor as a background process, keeping Sili(Con:)
  219. available as well.
  220.  
  221.  
  222. Appending Redirected Output
  223. ===========================
  224.  
  225. In addition to the normal CLI ">filename" convention for redirecting the
  226. standard output of a command to a file, Sili(Con:) allows ">>filename".
  227. In this case "filename" MUST already exist (or an error will be reported),
  228. and output from the command will be appended to its current contents.
  229. (As with the normal CLI, the redirection must immediately follow the
  230. command name itself; this is a requirement of the DOS syntax.)
  231.  
  232. For example:
  233.  
  234.           dir >alldirs df0: opt a
  235.           dir >>alldirs df1: opt a
  236.  
  237. gets one file containing a complete directory list of both your current
  238. disks.
  239.  
  240.  
  241. The Control Window
  242. ==================
  243.  
  244. Whenever the window labelled "Sili(Con:)" is active, characters typed on the
  245. keyboard will appear on the Command line.  If you enter a longer line than
  246. can be accomodated in the window it will scroll left.  A command may have
  247. up to 200 characters total (DOS limitation).  Typing a return will enter
  248. the command for execution.
  249.  
  250. You can edit the Command line before execution using standard string gadget
  251. conventions.  Left and right arrow keys move one character at a time left
  252. or right.  Holding the shift key down while typing a left or right arrow
  253. moves the cursor to that end of the line.  Backspace deletes successive
  254. characters to the left, DEL deletes to the right.  In addition, holding
  255. the Right Amiga key down while typing 'Q' restores the string to what it
  256. was initially (this will be empty, unless you are re-editing a previous
  257. command -- see below).  You can delete the whole string (and the Undo
  258. buffer!) at any time with CTRL-X (not string-gadget standard).
  259.  
  260. When you execute a command with return it is also entered in the "History
  261. List" displayed above the command line (unless it is a previous command
  262. that is being re-executed unchanged).  You can retrieve the just-executed
  263. command by typing the up-arrow once; further up-arrows retrieve preceding
  264. commands one by one.  You can move back down the list again with the
  265. down-arrow key.  A retrieved command can be executed unchanged by typing
  266. return, or it can be re-edited before execution.  A maximum of 50 commands
  267. will be kept in the history.  To see more of the history, use the sizing
  268. gadget to expand the window.
  269.  
  270. Instead of using the arrow keys, you may click directly on a command
  271. visible in the history window.  Clicking once retrieves it for editing.
  272. Double-clicking executes it immediately.  (You can't execute the Command
  273. line by double-clicking.  You can, however, reactivate the window by a
  274. single click on this line.)
  275.  
  276. If you want to preserve a command -- perhaps partially completed -- in
  277. the history list without actually executing it at that time, you can do so
  278. by holding down the shift key and typing return.  To delete a command
  279. from the list, move to that line with the arrow keys or the mouse and hold
  280. down the Right Amiga key while typing DEL.
  281.  
  282. If you want to move the Control window to the back as you execute a command,
  283. hold down the Right Amiga key as you type the return.  The command will
  284. execute in the normal way, but the Control window will disappear and the
  285. main DOS Console window will become active.  You can actually use
  286. Right-Amiga_Return at any time to push the Control window to the back
  287.  -- whether it is active or not -- but currently it will always make the
  288. DOS window active also.  If the Control window isn't active, any characters
  289. currently in the command line will remain there unexecuted; if it is, and
  290. you want to get the window out of the way without executing anything, make
  291. sure the Command line is empty first.  Once the window has been "put to
  292. sleep" with Right-Amiga-Return, you can wake it up again by
  293. Left-Amiga-Return as described in the next paragraph or by clicking the
  294. left mouse button within it.
  295.  
  296. You can bring the Sili(Con:) window to the front and make it active at ANY
  297. time by holding down the Left Amiga key and typing return.  Caution: if
  298. you are not in the WorkBench Screen at the time, you won't see this happen;
  299. you will have to switch to that screen with Left-Amiga-N.  Also, if
  300. the Command line happens to be already active (because characters have
  301. been typed while the window was active, for example) the Control window
  302. will not immediately come to the front;  a safe way out of this is to
  303. use shift-return to preserve and empty the Command line.
  304.  
  305. Any of the Interrupt combinations CTRL-C, CTRL-D, CTRL-E, OR CTRL-F that
  306. you type when the Control window is active will be transmitted to the
  307. running program, causing it to take whatever action it normally does in
  308. that situation. (Unless the program takes some other course, Sili(Con:)
  309. itself will eventually get any CTRL-D typed, and will then abort any
  310. command script that might be in progress at the time.)
  311.  
  312. A "feature" of the current version (in the true programmer's sense -- it
  313. appeared magically in the finished program...) is that typing Right-ALT
  314. while holding the Right Amiga key down will freeze the screen when the
  315. Sili(Con:) window is active.  To unfreeze it again, type the Amiga key
  316. (other keys may have temporarily paralysing effects -- I said this was
  317. a feature!).  Holding the LEFT Amiga key down and pressing Right-ALT will
  318. only freeze the screen while it is depressed.
  319.  
  320.  
  321. Sili(Con:) Messages
  322. ===================
  323.  
  324. Informational Messages:
  325.  
  326.   "running via `X' command"
  327.         The command is a script file with arguments.
  328.  
  329.   "running script file directly..."
  330.         The command is a script file that doesn't take arguments.
  331.  
  332.   "<programname> returned value <n>"
  333.         The return code from the program was <n> (rather than the usual 0).
  334.  
  335.   "exceeded FAILAT setting"
  336.         The return code was greater than the current value set by the
  337.         FAILAT command.  If a command script is in progress, it is aborted.
  338.  
  339.   "**BREAK**"
  340.         A CTRL-D interrupt was sent, aborting the command sequence.
  341.         (Note that "**BREAK" is reported by some programs if CTRL-C is sent.)
  342.  
  343.  
  344. Error Messages:
  345.  
  346.   "couldn't find <filename>"
  347.         No file matching the specified command was found in either the
  348.         assigned device list or the path.
  349.  
  350.   "Script file on path can't be EXECUTED"
  351.         'X' (EXECUTE) doesn't know about the DOS 1.2 path.
  352.  
  353.   "This file needs to be run with `X'"
  354.         A script file being run directly was found to contain a line
  355.         beginning with a period.
  356.  
  357.   "couldn't load <programname>"
  358.         A program file was apparently found, but couldn't be loaded.
  359.         You will normally only get this message because of a bug in the
  360.         DOS 1.2 RAM: handler.  AVOID having RAM: in the path or assigned
  361.         as "Cn:" (a subdirectory, such as "RAM:C", is all right).
  362.  
  363.   "Command string too long!"
  364.         The command had more than 200 characters.
  365.  
  366.   "already redirected!!"
  367.         More than one Input Redirection ("<"), or more than one Output
  368.         Redirection (">" or ">>"), was specified in one command.
  369.  
  370.   "couldn't open `<filename>'!!"
  371.         The <filename> specified as a redirection argument couldn't be
  372.         opened -- for instance if the mode was "append output" (">>") and
  373.         the file doesn't already exist.
  374.  
  375.   "NO SPACE FOR STACK -- ABORTING COMMAND!!"
  376.         Memory is too full to allocate stack space for the program to
  377.         be run.  (Depending on the situation, you may not be able to run
  378.         anything else either at this point.  If all else fails you can
  379.         click Sili(con:)'s Close gadget to regain its space.)
  380.  
  381.  
  382.  
  383.  
  384. Distribution
  385. ============
  386.  
  387. The program Sili(Con:) and this documentation are
  388.  
  389.                   Copyright (C) 1986,1987 by Peter J. Goodeve
  390.  
  391. You may copy it freely under the terms below, but it is NOT Public Domain.
  392. All Rights are reserved by the author.
  393.  
  394. Distribution to other parties is permitted provided that the distributor
  395. makes NO charge for such distribution, except that Bona Fide User Groups,
  396. or such other individuals or groups that have been notified in writing
  397. of permission to do so by the author, may impose a small charge to cover
  398. copying and materials costs.  This Document with its Copyright notice and
  399. distribution permissions MUST accompany all copies of the program.
  400.  
  401. Many months of effort have gone into its development, so if you use it
  402. you are strongly urged to send a donation to the author (please!):
  403.  
  404.          Peter Goodeve
  405.          3012 Deakin Street, #D
  406.          Berkeley, California 94705
  407.  
  408. $25 is suggested as the standard contribution, but whatever you feel is
  409. right.  Remember though that future development of this program depends
  410. almost entirely on your response, so if you like it... RESPOND!
  411. [I begin to feel like a PBS Pledge Night pitchperson -- but I guess
  412. the theory is pretty much the same, anyway.]
  413.  
  414. There's even a premium.  If I have your address and your $25, I will send
  415. a disk with the first significant update.  Also if you have suggestions or
  416. comments please send them.  They will be heeded.  When you send your
  417. donation, please include the version number of the program (in the CLI
  418. window when it starts up -- e.g. [8701.1]) so that I can keep track of
  419. things.
  420.  
  421. Coming back to future developments, I have in mind some significant
  422. extensions for "Second Sili(Con:)" -- things like managing multiple CLI
  423. processes (in their own windows) from a single control window, and an
  424. advanced type of environment variable -- that will take full advantage of
  425. the fundamental capabilities of our favorite machine.  When, how, and even
  426. if, this is distributed will depend on funding.  (It won't be a free
  427. update, though.)  So don't procrastinate... [Hey, PBS, how'm I doing?]
  428.  
  429. And finally, of course, because you are not asked to pay for this program
  430. unless you find it suitable,   NO WARRANTY OF ANY KIND IS PROVIDED,
  431. TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.
  432.  
  433. THE PROGRAM IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EITHER
  434. EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  435. OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK
  436. AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU, THE USER.
  437. SHOULD THE Sili(Con:) PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  438. NECESSARY SERVICING, REPAIR, OR CORRECTION.
  439.  
  440. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL PETER J. GOODEVE, AND/OR
  441. ANY OTHER PARTY WHO MAY LEGALLY DISTRIBUTE THIS PROGRAM, BE LIABLE TO YOU
  442. FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL,
  443. INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY
  444. TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  445. RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF
  446. THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAM), EVEN IF YOU HAVE BEEN
  447. ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER
  448. PARTY.
  449.  
  450.